Security News
Python Overtakes JavaScript as Top Programming Language on GitHub
Python becomes GitHub's top language in 2024, driven by AI and data science projects, while AI-powered security tools are gaining adoption.
focus-trap-react
Advanced tools
The focus-trap-react package is a React wrapper for the focus-trap library, which is used to manage focus within a DOM node. This is particularly useful for accessibility purposes, ensuring that keyboard navigation is contained within a specific area, such as a modal dialog or a dropdown menu.
Basic Focus Trap
This example demonstrates a basic focus trap that contains three buttons. When the focus is within this div, it will be trapped and cannot move outside of it using keyboard navigation.
import React from 'react';
import FocusTrap from 'focus-trap-react';
const BasicFocusTrap = () => (
<FocusTrap>
<div>
<button>Button 1</button>
<button>Button 2</button>
<button>Button 3</button>
</div>
</FocusTrap>
);
export default BasicFocusTrap;
Focus Trap with Initial Focus
This example shows a focus trap where the initial focus is set to a specific button using the `initialFocus` prop. When the focus trap is activated, the focus will automatically move to the button with the ID 'initial-focus'.
import React from 'react';
import FocusTrap from 'focus-trap-react';
const FocusTrapWithInitialFocus = () => (
<FocusTrap initialFocus='#initial-focus'>
<div>
<button id='initial-focus'>Initial Focus Button</button>
<button>Button 2</button>
<button>Button 3</button>
</div>
</FocusTrap>
);
export default FocusTrapWithInitialFocus;
Focus Trap with Return Focus
This example demonstrates a focus trap that will return the focus to the element that activated it once the trap is deactivated. The `returnFocus` prop ensures that the focus goes back to the button that was clicked to activate the focus trap.
import React, { useState } from 'react';
import FocusTrap from 'focus-trap-react';
const FocusTrapWithReturnFocus = () => {
const [isTrapActive, setIsTrapActive] = useState(false);
return (
<div>
<button onClick={() => setIsTrapActive(true)}>Activate Focus Trap</button>
{isTrapActive && (
<FocusTrap returnFocus>
<div>
<button onClick={() => setIsTrapActive(false)}>Deactivate Focus Trap</button>
<button>Button 2</button>
<button>Button 3</button>
</div>
</FocusTrap>
)}
</div>
);
};
export default FocusTrapWithReturnFocus;
react-focus-lock is another React component that provides a focus management solution. It ensures that the focus stays within a specified area, similar to focus-trap-react. However, react-focus-lock offers additional features like auto-locking and focus restoration, making it a more feature-rich alternative.
react-aria-modal is a React component for creating accessible modal dialogs. It includes focus trapping as part of its functionality, ensuring that keyboard navigation is contained within the modal. While it is more specialized for modal dialogs, it provides a robust solution for focus management within modals.
react-modal is a widely-used React component for creating modals. It includes built-in focus management to trap focus within the modal when it is open. While it is primarily focused on modal dialogs, it offers a comprehensive solution for focus trapping within modals.
A React component that traps focus.
This component is a light wrapper around focus-trap, tailored to your React-specific needs.
You might want it for, say, building an accessible modal?
Please read the focus-trap documentation to understand what a focus trap is, what happens when a focus trap is activated, and what happens when one is deactivated.
This module simply provides a React component that creates and manages a focus trap.
npm install focus-trap-react
dist/focus-trap-react.js
is the Babel-compiled file that you'll use.
React >= 16.3.0
As old and as broad as reasonably possible, excluding browsers that are out of support or have nearly no user base.
Focused on desktop browsers, particularly Chrome, Edge, FireFox, Safari, and Opera.
Focus-trap-react is not officially tested on any mobile browsers or devices.
โ ๏ธ Microsoft no longer supports any version of IE, so IE is no longer supported by this library.
๐ฌ Focus-trap-react relies on focus-trap so its browser support is at least what focus-trap supports.
๐ฌ Keep in mind that performance optimization and old browser support are often at odds, so tabbable may not always be able to use the most optimal (typically modern) APIs in all cases.
You wrap any element that you want to act as a focus trap with the <FocusTrap>
component. <FocusTrap>
expects exactly one child element which can be any HTML element or other React component that contains focusable elements. It cannot be a Fragment because <FocusTrap>
needs to be able to get a reference to the underlying HTML element, and Fragments do not have any representation in the DOM.
For example:
<FocusTrap>
<div id="modal-dialog" className="modal" >
<button>Ok</button>
<button>Cancel</button>
</div>
</FocusTrap>
<FocusTrap>
<ModalDialog okButtonText="Ok" cancelButtonText="Cancel" />
</FocusTrap>
You can read further code examples in demo/
(it's very simple), and see how it works.
Here's one more simple example:
const React = require('react');
const ReactDOM = require('react-dom'); // React 16-17
const { createRoot } = require('react-dom/client'); // React 18
const FocusTrap = require('focus-trap-react');
class Demo extends React.Component {
constructor(props) {
super(props);
this.state = {
activeTrap: false
};
this.mountTrap = this.mountTrap.bind(this);
this.unmountTrap = this.unmountTrap.bind(this);
}
mountTrap = () => {
this.setState({ activeTrap: true });
};
unmountTrap = () => {
this.setState({ activeTrap: false });
};
render() {
const trap = this.state.activeTrap
? <FocusTrap
focusTrapOptions={{
onDeactivate: this.unmountTrap
}}
>
<div className="trap">
<p>
Here is a focus trap
{' '}
<a href="#">with</a>
{' '}
<a href="#">some</a>
{' '}
<a href="#">focusable</a>
{' '}
parts.
</p>
<p>
<button onClick={this.unmountTrap}>
deactivate trap
</button>
</p>
</div>
</FocusTrap>
: false;
return (
<div>
<p>
<button onClick={this.mountTrap}>
activate trap
</button>
</p>
{trap}
</div>
);
}
}
ReactDOM.render(<Demo />, document.getElementById('root')); // React 16-17
createRoot(document.getElementById('root')).render(<Demo />); // React 18
React 18 introduced new behavior in Strict Mode whereby it mimics a possible future behavior where React might optimize an app's performance by unmounting certain components that aren't in use and later remounting them with previous, reused state when the user needs them again. What constitutes "not in use" and "needs them again" is as yet undefined.
Remounted with reused state is the key difference between what is otherwise expected about unmounted components.
v9.0.2 adds support for this new Strict Mode behavior: The trap attempts to detect that it has been remounted with previous state: If the active
prop's value is true
, and an internal focus trap instance already exists, the focus trap is re-activated on remount in order to reconcile stated expectations.
๐จ In Strict Mode (and so in dev builds only, since this behavior of Strict Mode only affects dev builds), the trap will be deactivated as soon as it is mounted, and then reactivated again, almost immediately, because React will immediately unmount and remount the trap as soon as it's rendered.
Therefore, avoid using options like onActivate, onPostActivate, onDeactivate, or onPostDeactivate to affect component state.
See this discussion for an example sandbox (issue description) where onDeactivate
was used to trigger the close of a dialog when the trap was deactivated (e.g. to react to the user clicking outside the trap with focusTrapOptions.clickOutsideDeactivates=true
).
The result can be that (depending on how you render the trap) in Strict Mode, the dialog never appears because it gets closed as soon as the trap renders, since the trap is deactivated as soon as it's unmounted, and so the onDeactivate
handler is called, thus hiding the dialog...
This is intentional: If the trap gets unmounted, it has no idea if it's being unmounted for good or if it's going to be remounted at some future point in time. It also has no idea of knowing how long it will be until it's remounted again. So it must be deactivated as though it's going away for good in order to prevent unintentional behavior and memory leaks (from orphaned document event listeners).
โ ๏ธ The
<FocusTrap>
component requires a single child, and this child must forward refs onto the element which will ultimately be considered the trap's container. Since React does not provide for a way to forward refs to class-based components, this means the child must be a functional component that uses theReact.forwardRef()
API.If you must use a class-based component as the trap's container, then you will need to get your own ref to it upon render, and use the
containerElements
prop (initially set to an empty array[]
) in order to provide the ref's element to it once updated by React (hint: use a callback ref).
๐ฌ The child is ignored (but still rendered) if the
containerElements
prop is used to imperatively provide trap container elements.
Example:
const React = require('react');
const { createRoot } = require('react-dom/client');
const propTypes = require('prop-types');
const FocusTrap = require('../../dist/focus-trap-react');
const container = document.getElementById('demo-function-child');
const TrapChild = React.forwardRef(function ({ onDeactivate }, ref) {
return (
<div ref={ref}>
<p>
Here is a focus trap <a href="#">with</a> <a href="#">some</a>{' '}
<a href="#">focusable</a> parts.
</p>
<p>
<button
onClick={onDeactivate}
aria-describedby="class-child-heading"
>
deactivate trap
</button>
</p>
</div>
);
});
TrapChild.displayName = 'TrapChild';
TrapChild.propTypes = {
onDeactivate: propTypes.func,
};
class DemoFunctionChild extends React.Component {
constructor(props) {
super(props);
this.state = {
activeTrap: false,
};
this.mountTrap = this.mountTrap.bind(this);
this.unmountTrap = this.unmountTrap.bind(this);
}
mountTrap() {
this.setState({ activeTrap: true });
}
unmountTrap() {
this.setState({ activeTrap: false });
}
render() {
const trap = this.state.activeTrap && (
<FocusTrap
focusTrapOptions={{
onDeactivate: this.unmountTrap,
}}
>
<TrapChild />
</FocusTrap>
);
return (
<div>
<p>
<button onClick={this.mountTrap} aria-describedby="function-child-heading">
activate trap
</button>
</p>
{trap}
</div>
);
}
}
const root = createRoot(container);
root.render(<DemoFunctionChild />);
Type: Object
, optional
Pass any of the options available in focus-trap's createOptions.
โ๏ธ This prop is only read once on the first render. It's never looked at again. This is particularly important if you use state-dependent memoized React Hooks (e.g.
const onActivate = useCallback(() => {...}, [something])
) for any of the focus-trap callbacks likeonActivate()
,onDeactivate()
,clickOutsideDeactivates()
, etc.If you need state-dependent callbacks, you have two options: (1) Use a React component
class
(as in the examples in this README) with bound member handlers, or (2) use a React Ref likeuseRef({ myState: 1 })
in your callbacks and manually manage your state.See #947 for more details.
โ ๏ธ See notes about testing in JSDom (e.g. using Jest) if that's what you currently use.
Type: Boolean
, optional
By default, the FocusTrap
activates when it mounts. So you activate and deactivate it via mounting and unmounting. If, however, you want to keep the FocusTrap
mounted while still toggling its activation state, you can do that with this prop.
See demo/demo-special-element.js
.
Type: Boolean
, optional
If you would like to pause or unpause the focus trap (see focus-trap
's documentation), toggle this prop.
Type: Array of HTMLElement
, optional
If specified, these elements will be used as the boundaries for the focus-trap, instead of the child. These get passed as arguments to focus-trap
's updateContainerElements()
method.
๐ฌ Note that when you use
containerElements
, the need for a child is eliminated as the child is always ignored (though still rendered) when the prop is specified, even if this prop is[]
(an empty array).Also note that if the refs you're putting into the array, like
containerElements={[ref1.current, ref2.current]}
, aren't resolved yet, resulting in[null, null]
for example, the trap will not get created. The array must contain at least one validHTMLElement
in order for the trap to get created/updated.
If containerElements
is subsequently updated (i.e. after the trap has been created) to an empty array (or an array of falsy values like [null, null]
), the trap will still be active, but the TAB key will do nothing because the trap will not contain any tabbable groups of nodes. At this point, the trap can either be deactivated manually or by unmounting, or an updated set of elements can be given to containerElements
to resume use of the TAB key.
Using containerElements
does require the use of React refs which, by nature, will require at least one state update in order to get the resolved elements into the prop, resulting in at least one additional render. In the normal case, this is likely more than acceptable, but if you really want to optimize things, then you could consider using focus-trap directly (see Trap2.js
).
โ ๏ธ JSDom is not officially supported. Your mileage may vary, and tests may break from one release to the next (even a patch or minor release).
This topic is just here to help with what we know may affect your tests.
In general, a focus trap is best tested in a full browser environment such as Cypress, Playwright, or Nightwatch where a full DOM is available.
Sometimes, that's not entirely desirable, and depending on what you're testing, you may be able to get away with using JSDom (e.g. via Jest), but you'll have to configure your traps using the focusTrapOptions.tabbableOptions.displayCheck: 'none'
option.
See Testing focus-trap in JSDom for more details.
See CONTRIBUTING.
In alphabetical order:
10.3.0
FAQs
A React component that traps focus.
The npm package focus-trap-react receives a total of 581,902 weekly downloads. As such, focus-trap-react popularity was classified as popular.
We found that focus-trap-react demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.ย It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Python becomes GitHub's top language in 2024, driven by AI and data science projects, while AI-powered security tools are gaining adoption.
Security News
Dutch National Police and FBI dismantle Redline and Meta infostealer malware-as-a-service operations in Operation Magnus, seizing servers and source code.
Research
Security News
Socket is tracking a new trend where malicious actors are now exploiting the popularity of LLM research to spread malware through seemingly useful open source packages.